home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Technology Seed / Jan. '98 ATS.toast / QuickTime™ 3.0b11 / QTPublicInterfaces / RIncludes / CodeFragments.r < prev    next >
Encoding:
Text File  |  1998-01-12  |  9.8 KB  |  268 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        CodeFragments.r
  3.  
  4.      Contains:    Public Code Fragment Manager Interfaces.
  5.  
  6.      Version:    Technology:    System 7
  7.                  Release:    QuickTime 3.0 Beta
  8.  
  9.      Copyright:    © 1992-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18.  
  19. #ifndef __CODEFRAGMENTS_R__
  20. #define __CODEFRAGMENTS_R__
  21.  
  22. #ifndef __CONDITIONALMACROS_R__
  23. #include "ConditionalMacros.r"
  24. #endif
  25.  
  26. #if TARGET_OS_MAC
  27. #define NoConflictCurrentVersionLabel currentVersion
  28. #else
  29. #define NoConflictCurrentVersionLabel currentVersion0
  30. #endif
  31.  
  32. /*
  33.     The 'cfrg' resource serves to inform the Process Manager and Code Fragment Manager
  34.     of code fragments present in this file.
  35.     
  36.     The 'cfrg' resource must have an ID of 0.  There can only be one 'cfrg' resource
  37.     per file, however, the trailing part of a 'cfrg' resource is an array of entries.
  38.     Each entry can be used to associate a name and architecture type to a specified 
  39.     code fragment. The names are used when the system searches for code fragments as 
  40.     named shared libraries.  There can be more than one cfrg array entry per code 
  41.     fragment, this is used to give a single code fragment more than one name.
  42.  
  43.     For Applications
  44.        The 'cfrg' is required to inform the Process Manager that there is a 
  45.        code fragment available.  One of the entries which has the architecture
  46.        type appropriate for the given machine (ie: pwpc, or m68k) should have the 
  47.        kIsApp usage designation.  The Process Manager will choose this code fragment 
  48.        over the traditional CODE 0.  The location of the code fragment (usually in 
  49.        the data fork) is described within the cfrg array entry.  
  50.        
  51.        For applications, the name is important only when an application has by name 
  52.        call backs, that is, exports for drop in extensions that import from the 
  53.        application.  Generally speaking, the name of the application is used for 
  54.        its 'cfrg' array entry.
  55.        
  56.     For Shared Libraries
  57.        The 'cfrg' is required to allow the Code Fragment Manager to find shared 
  58.        libraries. 
  59.        
  60.        Shared Libraries are libraries that satisfy link time imports, that are 
  61.        usually placed in the extensions folder; they are automatically connected to 
  62.        by the Code Fragment Manager at application launch time.  Shared Libraries
  63.        must have the file type 'shlb'.  The usage field is set to kIsLib for shared 
  64.        libraries.
  65.  
  66.  
  67.     Plug-in extensions (code fragments packaged in various application specific ways)
  68.     are that loaded programaticallly by the application do not require the file type 
  69.     'shlb' and a cfrg resource, but may use some similar mechanism that is application
  70.     specific and developer defined.
  71.  
  72.  
  73.     There are two versions of the 'cfrg' resource template.
  74.  
  75.     The original version (cfrg_RezTemplateVersion = 0) is appropriate for 
  76.     applications and most shared libraries.
  77.     
  78.     The second version (cfrg_RezTemplateVersion = 1) is needed only when the code 
  79.     fragment will be found using the new CFM/SOM search mechanisms. It
  80.     contains additional information.
  81.     
  82.     In order to mix both kinds of entries in one 'cfrg' resources, the second
  83.     version of the template contains a switch statement for specifying which
  84.     kind of entry is being generated.  The following example shows how to 
  85.     convert a cfrg_RezTemplateVersion=0 format to a cfrg_RezTemplateVersion=1
  86.     format 'cfrg' resource:            
  87.  
  88.  
  89.     When cfrg_RezTemplateVersion=0 use:
  90.     
  91.                 resource 'cfrg' (0) {
  92.                     {
  93.                         kPowerPCCFragArch, kIsCompleteCFrag, kNoVersionNum, kNoVersionNum,
  94.                         kDefaultStackSize, kNoAppSubFolder,
  95.                         kApplicationCFrag, kDataForkCFragLocator, kZeroOffset, kCFragGoesToEOF,
  96.                         "My Application",
  97.                     }
  98.                 };
  99.                 
  100.     when cfrg_RezTemplateVersion=1 use:
  101.                 resource 'cfrg' (0) {
  102.                     {
  103.                         regularEntry {        // <--- add this line     
  104.                             kPowerPCCFragArch, kIsCompleteCFrag, kNoVersionNum, kNoVersionNum,
  105.                             kDefaultStackSize, kNoAppSubFolder,
  106.                             kApplicationCFrag, kDataForkCFragLocator, kZeroOffset, kCFragGoesToEOF,
  107.                             "My Application",
  108.                         }                    // <--- and this line 
  109.                     }
  110.                 };
  111.                 
  112.     The compiled binary resource is identical.
  113.     
  114.     The extended form allows specification of an OSType and 4 Str255s that are 
  115.     used as criterea in searching for libraries that satisfy some contstraints.
  116.     For example, a SOM class library that is a particular sub-class of the 
  117.     "ClassXYZ" base class, might be represented as :
  118.                 resource 'cfrg' (0) {
  119.                     {
  120.                         extendedEntry {
  121.                             kPowerPCCFragArch, kIsCompleteCFrag, kNoVersionNum, kNoVersionNum,
  122.                             kDefaultStackSize, kNoAppSubFolder,
  123.                             kImportLibraryCFrag,kOnDiskFlat,kZeroOffset,kCFragGoesToEOF,
  124.                             "MyLibName",    // standard internal name: used by CFM 
  125.                             // start of extended info 
  126.                             kFragSOMClassLibrary,
  127.                             "ClassXYZ",
  128.                             "",
  129.                             "",
  130.                             "My Name"        // external name: may be seen by user 
  131.                         }
  132.                     }
  133.                 };
  134.     Using the new CFM/SOM search functions, one could search for all som
  135.     class libraries that inherit from "ClassXYZ".
  136. */
  137.  
  138.  
  139. /*---------------------------cfrg • CodeFragments---------------------------*/
  140. /*
  141.     cfrg_RezTemplateVersion:
  142.         0 - original                         <-- default
  143.         1 - extended for SOM 
  144. */
  145. #ifndef cfrg_RezTemplateVersion
  146.     #ifdef UseExtendedCFRGTemplate                            /* grandfather in use of “UseExtendedCFRGTemplate” */
  147.         #define cfrg_RezTemplateVersion 1
  148.     #else
  149.         #define cfrg_RezTemplateVersion 0
  150.     #endif
  151. #endif
  152.  
  153.  
  154. /* grandfather in old names for fields */
  155. #define kIsLib                 kImportLibraryCFrag
  156. #define kIsApp                 kApplicationCFrag
  157. #define kIsDropIn             kDropInAdditionCFrag
  158. #define kInMem                 kMemoryCFragLocator
  159. #define kOnDiskFlat         kDataForkCFragLocator
  160. #define kOnDiskSegmented     kResourceCFragLocator
  161. #define kPowerPC             kPowerPCCFragArch
  162. #define kMotorola             kMotorola68KCFragArch
  163. #define kFullLib             kIsCompleteCFrag
  164. #define kUpdateLib             kFirstCFragUpdate
  165. #define kWholeFork             kCFragGoesToEOF
  166.  
  167.  
  168. type 'cfrg' {
  169.    longint = 0;            /* reserved - in use */
  170.    longint = 0;            /* reserved - in use */
  171.    longint = 1;            /* cfrgVersion       */
  172.    longint = 0;            /* reserved - in use */
  173.    longint = 0;            /* reserved - in use */
  174.    longint = 0;            /* reserved - free   */
  175.    longint = 0;            /* reserved - free   */
  176.    longint = $$CountOf (memberArray);
  177.    Array memberArray {
  178.      memberStart:
  179.       align long;
  180.       
  181. #if cfrg_RezTemplateVersion == 1
  182.       switch{
  183.       case regularEntry:
  184. #endif    
  185.         literal longint archType, kPowerPCCFragArch = 'pwpc', kMotorola68KCFragArch = 'm68k';
  186.         longint         updateLevel, kIsCompleteCFrag = 0, kFirstCFragUpdate = 1;
  187.         longint         currentVersion, kNoVersionNum = 0;
  188.         longint         oldDefVersion, kNoVersionNum = 0;
  189.         longint         appStackSize, kDefaultStackSize = 0;
  190.         integer         appSubFolderID, kNoAppSubFolder = 0;
  191.         byte            usage, kImportLibraryCFrag = 0, kApplicationCFrag = 1, 
  192.                             kDropInAdditionCFrag = 2, kStubLibraryCFrag = 3, 
  193.                             kWeakStubLibraryCFrag = 4;
  194.         byte            where, kMemoryCFragLocator = 0, kDataForkCFragLocator = 1, 
  195.                             kResourceCFragLocator = 2;
  196.         longint         offset, kZeroOffset = 0, kRSEG = 'rseg';
  197.         longint         length, kCFragGoesToEOF = 0, kSegIDZero = 0;
  198.         longint         = 0;      /* reserved - free */
  199. #if cfrg_RezTemplateVersion == 1
  200.         integer         = 0;      /* reserved - free */
  201.         key integer     = 0;      /* no cfrg extensions */
  202. #else
  203.         longint         = 0;      /* reserved - free   */
  204. #endif
  205.         integer         = (memberEnd[$$ArrayIndex(memberArray)] - memberStart[$$ArrayIndex(memberArray)]) / 8;
  206.         pstring;        /* member name */
  207.  
  208.  
  209. #if cfrg_RezTemplateVersion == 1
  210.       case extendedEntry:
  211.         literal longint archType, kPowerPCCFragArch = 'pwpc', kMotorola68KCFragArch = 'm68k';
  212.         longint         updateLevel, kIsCompleteCFrag = 0, kFirstCFragUpdate = 1;
  213.         longint         currentVersion, kNoVersionNum = 0;
  214.         longint         oldDefVersion, kNoVersionNum = 0;
  215.         longint         appStackSize, kDefaultStackSize = 0;
  216.         integer         appSubFolderID, kNoAppSubFolder = 0;
  217.         byte            usage, kImportLibraryCFrag = 0, kApplicationCFrag = 1, 
  218.                             kDropInAdditionCFrag = 2, kStubLibraryCFrag = 3, 
  219.                             kWeakStubLibraryCFrag = 4;
  220.         byte            where, kMemoryCFragLocator = 0, kDataForkCFragLocator = 1, 
  221.                                 kResourceCFragLocator = 2;
  222.         longint         offset, kZeroOffset = 0, kRSEG = 'rseg';
  223.         longint         length, kCFragGoesToEOF = 0, kSegIDZero = 0;
  224.         longint         = 0;      /* reserved - free */
  225.         integer         = 0;      /* reserved - free */
  226.         key integer     = 1;      /* one extension   */
  227.         integer         = (memberEnd[$$ArrayIndex(memberArray)] - memberStart[$$ArrayIndex(memberArray)]) / 8;
  228.         pstring;        /* member name */
  229.         align long;     /* match size to C structure size */
  230.         extensionStart: 
  231.         integer          = 0x30ee;       /* magic # signifies this extended cfrg entry format */
  232.         integer         = (extensionEnd[$$ArrayIndex(memberArray)] - extensionStart[$$ArrayIndex(memberArray)]) / 8;
  233.         literal longint libKind, 
  234.                     kFragDocumentPartHandler     = 'part',
  235.                     kFragSOMClassLibrary         = 'clas',
  236.                     kFragInterfaceDefinition     = 'libr',
  237.                     kFragComponentMgrComponent    = 'comp';
  238.                     /* others allowed, need to be a DTS registered OSType */
  239.         pstring;          /* qualifier 1: 
  240.                             'part' : part handler type
  241.                             'clas' : base class name
  242.                             'libr' : interface definition name
  243.                             'comp' : component kind
  244.                       */
  245.  
  246.  
  247.         pstring;          /* qualifier 2:
  248.                             'part' : part handler sub type ?
  249.                             'clas' : not used
  250.                             'libr' : not used
  251.                             'comp' : component sub kind
  252.                       */
  253.         pstring;          /* infoStr, optional information depending on libKind */
  254.         pstring;          /* intlName, an internationalizable string that can
  255.                          be displayed to the user on the screen */
  256.         align long;
  257.        extensionEnd:
  258.       };
  259. #endif
  260.      align long;
  261.      memberEnd:
  262.    };
  263. };
  264.  
  265.  
  266. #endif /* __CODEFRAGMENTS_R__ */
  267.  
  268.